<HTML><HEAD><TITLE>printf(+Format, ?ArgList)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term I/O</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>printf(+Format, ?ArgList)</H1>
The arguments in the argument list ArgList are interpreted according to the
Format string and the result is printed to the output stream.


<DL>
<DT><EM>Format</EM></DT>
<DD>String or Atom.
</DD>
<DT><EM>ArgList</EM></DT>
<DD>List or any Term.
</DD>
</DL>
<H2>Description</H2>
   Format is either an atom or a string which can contain control sequences
   of the form

<P>
   %AC or %NC

<P>
   where C is a single letter format control option and A or N are optional
   parameters.  Any characters that are not part of a control sequence are
   written to the output stream.

<DL>
  <DT>A<DD>
    A may consist of:
    a minus sign, a plus sign, a space , the character '#', a digit string
    (or a '*'), a period, a digit string (or a '*') and a length modifier 'l'.
<P>
    This substring A is interpreted in the same way as in the 'C' routine
    printf(3).

  <DT>N<DD>
    The argument N has to be a non-negative integer.
</DL>

   If the character '*' appears inside A or N it is replaced by the next
   argument from ArgList.
<P>

   ArgList is a list of arguments which will be interpreted and possibly
   printed by format control options.  If there is only one argument, it
   need not be in a list.

<P>
   The elements from the argument list ArgList are interpreted according to
   the following control options and printed to the output.  The arguments
   must be of the type specified, or the corresponding event will be
   raised.

<DL>
  <DT>%<STRONG>a</STRONG><DD>
    The argument has to be an atom and is passed to write/1.

  <DT>%<STRONG>A</STRONG><DD>
    The argument has to be an atom. All its characters are converted
    to upper case and the result is printed.

  <DT>%N<STRONG>c</STRONG><DD>
    The argument has to be a numeric ASCII code and is printed N times.  If
    N is omitted, it defaults to 1.

  <DT>%A<STRONG>d</STRONG><DD>
    The argument has to be an integer and is printed according to the
    substring A in signed decimal notation.

  <DT>%A<STRONG>o</STRONG><DD>
    The argument has to be an integer and is printed according to the
    substring A in unsigned octal notation.

  <DT>%A<STRONG>u</STRONG><DD>
    The argument has to be an integer and is printed according to the
    substring A in unsigned decimal notation.

  <DT>%A<STRONG>x</STRONG><DD>
    The argument has to be an integer and is printed according to the
    substring A in unsigned hexadecimal notation.  (The letters abcdef are
    used.)

  <DT>%A<STRONG>X</STRONG><DD>
    The argument has to be an integer and is printed according to the
    substring A in unsigned hexadecimal notation.  (The letters ABCDEF are
    used.)

  <DT>%A<STRONG>e</STRONG><DD>
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential notation.('e' is used for
    exponentiation)

  <DT>%A<STRONG>E</STRONG><DD>
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential notation.  ('E' is used for
    exponentiation)

  <DT>%A<STRONG>f</STRONG><DD>
    The argument has to be a floating-point number and is printed according
    to the substring A in non-exponential form.

  <DT>%A<STRONG>g</STRONG><DD>
    The argument has to be a floating-point number and is printed according
    to the substring A in exponential or non-exponential form, whichever
    gives the best precision in minimum space.('e' is used for
    exponentiation)

  <DT>%A<STRONG>s</STRONG><DD>
    The argument has to be a string or an atom and is printed according to
    the substring A.

  <DT>%N<STRONG>r</STRONG><DD>
    The argument has to be an integer and it is printed as signed in radix
    N using the digits 0-9 and letters a-z.  N must be greater than 1 and
    less than 37.  If N is not specified, it defaults to 8.

  <DT>%N<STRONG>R</STRONG><DD>
    The argument has to be an integer and it is printed as signed in radix
    N using the digits 0-9 and letters A-Z. N must be greater than 1 and
    less than 37.  If N is not specified, it defaults to 8.

<P>
   The following control options can interpret arguments of any type.

  <DT>%N<STRONG>i</STRONG><DD>
    N arguments are ignored.  If N is omitted, it defaults to 1.

  <DT>%<STRONG>k</STRONG><DD>
    The argument is passed to display/1.  It is a synonym for %O.w.

  <DT>%<STRONG>p</STRONG><DD>
    The argument is passed to print/1.  It is a synonym for %Pw.

  <DT>%<STRONG>q</STRONG><DD>
    %q

<DD>
    The argument is passed to writeq/1.  It is a synonym for %QDvw.

  <DT>%<STRONG>w</STRONG><DD>
   The argument is by default passed to write/1.
   However, the %w format recognises a number of control characters,
   placed between the percent sign and w.  They give the user full
   control over the various possibilities of printing Prolog terms.
   A number immediately after the percent sign determines the depth
   to which the term is printed, if an asterisk is used instead, the
   depth is taken from the next argument in ArgList. The default depth
   is determined by the setting of the (stream-specific or global)
   print_depth flag.
   After the optional depth, the following modifiers are recognized:

<DL>
      <DT><STRONG>O</STRONG><DD>
	omit operator declarations.  All terms are written in the canonical
	notation without operators.

      <DT><STRONG>Q</STRONG><DD>
	quote atoms and strings if necessary.

      <DT><STRONG>.</STRONG><DD>
	write lists in the dot functor notation rather than using the
	square bracket notation, e.g. .(1, .(2, [])) rather than [1, 2].

      <DT><STRONG>G</STRONG><DD>
	print the term as a goal, i.e. goal write transformations will be
	taken into account.

      <DT><STRONG>P</STRONG><DD>
	call the user-defined predicate portray/1, 2 in the way print/1, 2
	does.

      <DT><STRONG>D</STRONG><DD>
	disregard the depth restriction of the print-depth flag and print
	the whole term.

      <DT><STRONG>U</STRONG><DD>
	call portray/1, 2 even on variables.  This is to be used in
	conjunction with the P option.  Note that attributed variables
	are always portrayed.

      <DT><STRONG>V</STRONG><DD>
	print the full variable name, if available, either in the form
	Name_Number, e.g. Alpha_132, or Name#Number, if the variable had
        been given a name via lib(var_name). This is necessary to 
        distinguish different variables with the same name.

      <DT><STRONG>v</STRONG><DD>
	print only the short variable form, i.e. even when available, the
	variable name is not printed.  This is useful if a term should be
	written and read back in several times.  If neither V nor v is
	specified, variables are printed only with their name, if it is
	available.  Variable without names are always printed in the v form.

      <DT><STRONG>_</STRONG><DD>
	print every variable as a simple underscore. Any information about
	multiple occurrences of a variable is lost with this format. It is
	mainly useful to produce output that can be compared easily with
	the output of a different Eclipse session.

      <DT><STRONG>I</STRONG><DD>
	any term of the form '$VAR'(N), where N is a non-negative integer,
	is printed as a variable name consisting of a capital letter
	followed by a number. The capital letter is the ((N mod 26)+1)st
	letter of the alphabet, and the integer is N//26.
	If N is an atom, this atom gets printed instead of the term.

      <DT><STRONG>K</STRONG><DD>
	don't print blank space (around operators, after commas, etc.)
	unless necessary.

      <DT><STRONG>M</STRONG><DD>
	print the full contents of all variable attributes.  This is
	necessary if the term is to be written out and read back in.

      <DT><STRONG>m</STRONG><DD>
	variable attributes are printed using the corresponding print
	handlers.  If neither M nor m is specified, attributed variables
	are printed as variables, without any attribute.

      <DT><STRONG>N</STRONG><DD>
	print newline (NL) characters as newlines rather than as an
	escape sequence, even when they occur in quoted atoms or strings.
	This only makes sense together with the Q modifier.

      <DT><STRONG>T</STRONG><DD>
	do not apply any write transformations.

      <DT><STRONG>C</STRONG><DD>
	print the term as a clause, i.e.  clause macros will be taken into
	account.
</DL>

  <DT>%<STRONG>W</STRONG><DD>
    Like %w, but the stream's default output options are taken into
    account, unless overridden by the format options specified here.
    Note in particular that a default setting may be cancelled by
    prefixing the format character with a minus sign. E.g. if the stream
    defaults specify that quotes should be printed (quoted(true)), this
    can be overridden by a %-QW format string.

</DL>
   The following control options do not have a corresponding argument.
<DL>
  <DT>%<STRONG>%</STRONG><DD>
    One % is printed.

  <DT>%N<STRONG>n</STRONG><DD>
    N newline sequences are printed.  If N is omitted it defaults to 1.
    Which newline characters are printed depends on the setting of the
    stream's end_of_line property. If the stream's flush-property is set
    to end_of_line, the stream is also flushed.

  <DT>%N<STRONG>t</STRONG><DD>
    N tab characters are printed.  If N is omitted it defaults to 1.

  <DT>%<STRONG>b</STRONG><DD>
    The output buffer is flushed, the data is written into the file.
</DL>

<H3>Modes and Determinism</H3><UL>
<LI>printf(+, ?) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Format is not an atom or a string.
<DT><EM>(5) type error </EM>
<DD>ArgList contains argument whose type does not correspond to    the control sequence.
<DT><EM>(7) string contains unexpected characters </EM>
<DD>Format is not correct, it contains too many asterisks or a    control character is missing or there is a redundant character before    the control character.
<DT><EM>(8) bad argument list </EM>
<DD>ArgList has not enough or too many arguments.
</DL>
<H2>Examples</H2>
<PRE>   Equivalent to printf(output, Format, ArgList).  (see printf/3 for
   details).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/ioterm/display-1.html">display / 1</A>, <A HREF="../../kernel/ioterm/display-2.html">display / 2</A>, <A HREF="../../kernel/ioterm/print-1.html">print / 1</A>, <A HREF="../../kernel/ioterm/print-2.html">print / 2</A>, <A HREF="../../kernel/ioterm/printf-3.html">printf / 3</A>, <A HREF="../../kernel/ioterm/sprintf-3.html">sprintf / 3</A>, <A HREF="../../kernel/ioterm/write-1.html">write / 1</A>, <A HREF="../../kernel/ioterm/write-2.html">write / 2</A>, <A HREF="../../kernel/ioterm/writeq-1.html">writeq / 1</A>, <A HREF="../../kernel/ioterm/writeq-2.html">writeq / 2</A>
</BODY></HTML>
